8. The Network protocol

8.1 Generalities

This is an incomplete description of the Quake Network Protocol used in Quake version 1.01. The protocol used in Quake Worlds will probably be rather different, and hopefully much more optimised.

The network protocol described below is not derived from documents by id software, so it's likely to be incomplete (or even wrong).

The messages exchanged by the Quake client and servers are not really complex to understand, but they are quite numerous, and of heterogeneous structure. Please read the example of network session, before trying to emulate a Quake client or server.

Since the messages in the .DEM files have exactly the same format as some of the network protocol messages, it is highly recommended that you also take a look at the DEM specs by Uwe Girlich.

When describing the content of messages, we will use the same conventions as in the DEM specs:

ReadString() = read a sequence of characters, terminated by NULL ('\0')
ReadAngle()  = read a byte, and multiply it by 360.0 / 256.0 to make it into degrees.
ReadChar()   = read a signed integer, on one byte.
ReadShort()  = read a signed integer, on two bytes, Big Endian order (Intel order).
ReadLong()   = read a signed integer, on four bytes, Big Endian order (Intel order).
ReadFloat()  = read a floating point number, on four bytes, Big Endian order (Intel order).

8.2 Control messages

The structure of control messages is the following:

typedef struct
{ short Type=0x8000;           // (Little Endian) Type of message.
  short Length;                // (Little Endian) Length of message, header included. 
  char  message[Length-4];     // The contents of the message.
} MSGHEADER;

Warning: the fields Type and Length are in Little Endian order (most significant byte first). To read them on an Intel processor, you must swap the higher and lower bytes.

The structure of the message fields is: a single-byte code, followed by code-dependant informations. The following table details this information.

Thanks to A.Oliver for the description of the control requests 0x3, 0x4, 0x82, 0x84, 0x85 in the Unofficial Quake Network Protocol Specs 1.01.

GameName = ReadString();      // = "QUAKE"
ProtocolVersion = ReadChar(); // = 3

GameName = ReadString();      // = "QUAKE"
ProtocolVersion = ReadChar(); // = 3

Player = ReadChar();      // player number, from 0 to 15

Rule = ReadString();     // name of the previous rule
// To pool all rule names, start with Rule = "", then continue
// with the rule name obtained in the reply,
// until an empty reply is received.

Port    = ReadLong();    // Client's personal UDP or IPX port number

Reason  = ReadString();  // Reason for rejecting the request

Address = ReadString();  // Server address, in ascii
Hostname= ReadString();  // name of the host machine
Mapname = ReadString();  // name of the current map
Players = ReadChar();    // current number of players
Maximum = ReadChar();    // maximum number of players
ProtocolVersion = ReadChar(); // = 3

Player  = ReadChar();    // player number, from 0 to 15
Name    = ReadString();  // name of the player
Colors  = ReadChar();    // shirt/pants colors
ReadChar();              // zero ???
ReadChar();              // zero ???
ReadChar();              // zero ???
frags   = ReadLong();    // Number of frags
time    = ReadLong();    // Connection time in seconds 
Address = ReadString();  // ip address and port, or "LOCAL".

// If this message is void, there are no more rules.
Rule    = ReadString();  // Name of the rule
Value   = ReadString();  // Ascii value of the requested rule
// Rule is one of "sv_maxspeed", "sv_friction", "sv_gravity",
// "noexit", "teamplay", "timelimit" or "fraglimit".

Note: the control messages contain only one message part (one single code, followed by code-dependant information). But there could be many parts, though it has never been observed.

8.3 Games messages

Every network packet send via UDP (and probably IPX) has the same header:

typedef struct
{ short Type;                  // (Little Endian) Type of message.
  short Length;                // (Little Endian) Length of message, header included. 
  long  Order;                 // (Little Endian) Order of emission.
  char  message[Length-8];     // The contents of the message.
} MSGHEADER;

Warning: The fields Type, Length and Order are in Little Endian order (most significant byte first). To read them on an Intel processor, you must swap the higher and lower bytes.

8.3.1 Types of messages

8.3.2 Usage of messages

• Reliable messages are used to send the game initialisation informations, that would crash the client if they were not received correctly. But that kind of message is not sent anymore, once game play has started.
  The field Order is used to keep track of the order number of the last message sent, and to acknowledge a message received.
• Update messages are used to send game update informations, like movement of entities, and movement of the player. They are the only messages used during game play, until the level ends.
  The fields Order is increasing by one with every message, but it doesn't seem to be used. Maybe it allows a Client to detect if a previous message has been lost, and should be repeated.

8.3.3 Interpretation of the message contents

The message content is made of a single byte code, followed by some code-dependent data, and then followed by another byte code, and so on until the end of the message.

That means you need to know how to interpret all the possible byte codes to read a single message. That also means that if you make a mistake in the encoding of a single code, then all the rest will be screwed up, and can eventually crash the game. So trust it on luck!

To make matter worse, the byte codes must be interpreted differently, wether the message comes from a game Server or from a game Client.

8.4 Format of client messages

This is the format of the message field, for messages sent by a game client. This field is an unstructured set of bytes, that must be read one by one in order to decode all the parts of the message.

First, you should read one byte (the message code). Then, depending, on this code, you must read zero or more bytes, depending on the code. That gives you one prt of the message. To read the next part, read one byte, that gives you a code, and so on... until the end of the message field.

Stop at the first unrecognised code, it's no use to continue if you have lost your marks.

8.4.1 Codes for client messages

Void

Void

Void

ActionTime= ReadFloat();  
TiltAngle = ReadAngle();  
YawAngle  = ReadAngle();  
FlipAngle = ReadAngle();  
SpeedFront = ReadInt16();  
SpeedRight = ReadInt16();  
SpeedUp    = ReadInt16();  
Flag     = ReadChar();   
// Flag & 1: fire.
// Flag & 2: jump.
Impulse   = ReadChar();   
// Impulse command

Command = ReadString()

Void

8.4.2 About the player movement order

The angles transmitted by a player movements are directly the angles set by the player, whether via the mouse or via the look up/down keys. Note that there is a flip angle indicated, but since no player command can possibly act on it, it's always zero. Too bad... but this is not DESCENT.

The speed are ordinary signed integers, that seem to indicate a desired speed in units per second. Experiment shows that when the player places an order for +200 forward speed (typical run order), then the player accelerate, until the speed stabilises at +200 coordinates per second (which makes it 10 coordinates per update, that happen every 20th of second).

This behavior proves that this parameter is a speed, not an acceleration. Well, this is a walking or swimming dude after all, not a ship in the void. He's moving in a world where friction is preponderant. Acceleration is only simulated, in the sense that you cannot change to arbitrary speed values in no time. On ordinary ground, accelerations seem limited to about 1000 to 15000 units/second▓.

8.5 Format of server messages

The game messages sent by the Quake server are exactly the same as the ones used in the demo files (.DEM), so they will not be repeated here. Look at the DEM file specifications.

A single Quake server message contains exactly the same informations as those contained in a .DEM file block of messages. That is rather logical, since they certainly didn't create a new format just for the .DEM files, but used the network protocol instead.

Let's just recall those useful orders:

Code	Message	Informations	Explanations
0x19	Set signon state	state = ReadChar()	This sets the signon state, a state variable that is used to guide the intialisation of a client. 1 = PRESPAWN (prepare for entity spawning). 2 = INIT LIGHT EFFECTS 3 = START 3D RENDERING (run the game).
0x80-0xFF	Entity update	Based on mask. Very complicated.	This is the standard message that updates the position, angles, frame and models of a given entity.

8.6 Network session example

Here are some examples of how a Quake server and a Quake client interact. They sumarise an actual game session, observed by intercepting the game packets.

8.6.1 Request informations about the game

Those messages are sent to and from the PUBLIC UDP PORT of the server (which is 26000 by default).

Client sends a Request Informations message,
	with game name QUAKE.
Server sends a Give Informations message,
        with indications on the current map, number of players...

Note: Those messages can be sent to interrogate a given Quake server, without really disturbing it. Of course, if you flood a Quake server with such messages, it might slow down.

8.6.2 Establish a game session

Those messages are sent to and from the PUBLIC UDP PORT of the server (which is 26000 by default).

Client sends a Connect message,
	with game name QUAKE.
Server sends an Accept message,
	containing the identifier of a PERSONAL UDP PORT for the client.
        Client now expects server message coming from the PERSONAL UDP PORT

Warning: after it replied with an Accept message, the game server will only use a PERSONAL UDP PORT to communicate with a given client. The server PUBLIC UDP PORT is not used anymore to talk to that client. It can only be used by clients that are not connected yet.

8.6.3 Prepare the client for the game (precache)

Server sends a big message that contains:
  - the server banner "VERSION 1.01 SERVER (21456 CRC)"
  - a server info message (code 0x0B) with map name, and precached models and sounds
  - an indication that client should move to PRESPAWN state.
Client sends a No Operation (code 0x01)
Client sends a console command (code 0x04) "prespawn", indicating prespawn is finished.
Server sends a big message that contains order to spawn static sounds and static entities
  - For all the static entities described in the .BSP file, 
     One "Spawn Static entity" order, and possibly a Static Sound order.
Client sends a player information message:
  - console order "name PLAYER\n" (where PLAYER is the player name)
  - console order "color 0 0\n"   (shirt and pants colors)
  - console order "spawn " to indicate the client is ready to play.
Server sends a big message:
  - For each possible player in the game (including those not connected):
     a set of orders UPDATE NAME, UPDATE FRAGS, UPDATE COLORS
  - For each of the 64 light style:
     a SET LIGHT STYLE message.
  - an UPDATE STATE message for total and found monsters and secrets
  - a SET ANGLE order, to orient the player's view
  - a CLIENT DATA order, fix the status bar display
  - an order to move to Start 3d Rendering state.
  - a last update NAMe, FRAGS, and COLORS, for the client.
Client sends a console message "begin".

8.6.4 Run the game with the client

Every 50 milliseconds,
Server sends an update message, that contains:
  - an indication of the game time
  - a CLIENT DATA order, to fix the status bar display (mostly useless)
  - an UPDATE ENTITY order for each entity possibly in sight
     if the entity has not changed, only minimal informations will be sent.

Each time the player moves,
Client sends an update message containing:
  - a movement order.

8.7 Making a fake client (aka Bot)

These are only partial informations, but that should be enough for a start.

Connecting the fake client and the Quake server

Here is a simplified connection procedure, to register into a Quake server.

1. Client sends Connect message to the server, on his public port (usually 26000).
2. Server replies with an Accept message, that contains the name of an UDP port that is dedicated to the client (usually in the range 1025-1200).
3. Now, to talk the the server, the client sends messages only to the dedicated UDP port. The public UDP port becomes useless for the client.
4. From now on, the client must acknowledge all the message parts and message last parts that are sent by the server, otherwise the server will repeat the same message forever and no further progress will be made.
5. The client waits for a long message that contains and order to set the signon state to 1 (prespawn).
6. Client sends a message containing a single Console order:

       "prespawn".       (there is no return character at the end)
   

7. The client waits for a long message that contains and order to set the signon state to 2 (init light effects).
8. Client sends a message containing three Console orders:

       "name player\n"   ('\n' is the return character)
       "color 0 0\n"     ('\n' is the return character)   
       "spawn "          (there is white space at the end).
   

9. The client waits for a long message that contains and order to set the signon state to 3 (start 3D rendering).
10. Client sends a message containing a single Console order:

        "begin"           (there is no return character at the end).
    

11. From now on, the game is running, and the client starts receiving a flood of update messages.

The fake client at play

How to send movement orders:

1. Server sends an Update message, containing entity update orders for all the entities in sight.
2. Client calculates whatever clever moves he wishes.
3. Client sends an Update message, containing a single Movement order.

How to send orders on the server console:

1. The client sends a reliable message containing a Console order.

A client receives no update for the entities not in sight, so you cannot cheat and make some radar that sees through walls. BUT you can of course make a simple bot that will turn immediatly toward any enemy coming in his back. And will of course avoid any rockets, or even straffe out of the line of sight of any hostile player.

Beware that the client must rely on himself alone to guess the geometry of the room he is in. The best is of course to load the .BSP for the level, and to keep track of the position of every entities, so as to know which paths are possible, and which are not. But you will soon discover that the .BSP per se is not enough to code a good behavior for a Bot, because there is no trace of the links between the rooms.

Leaving the server

Here is the cleanest way to leave the server:

1. Client sends a Disconnect order.